package com.github.xtranslation.core.core;


import com.github.xtranslation.core.repository.TransRepository;
import lombok.Getter;

import java.lang.annotation.Annotation;
import java.lang.reflect.Field;
import java.util.List;

/**
 * TransFieldMeta: 翻译字段元数据
 * <p>
 * 该类封装了翻译字段的所有元数据信息，包括源字段、目标字段、翻译键值、翻译仓库等。
 * 用于在翻译过程中提供必要的上下文信息。
 * </p>
 *
 * @author zhangxiaoxiang
 * @since 2025/7/27
 */
@Getter
public class TransFieldMeta {

    /**
     * 源字段名，即包含原始值的字段名称
     * <p>
     * 例如：userId（包含用户ID的字段）
     * </p>
     */
    private final String trans;

    /**
     * 源字段对象，即包含原始值的字段
     * <p>
     * 例如：UserDto类中的userId字段
     * </p>
     */
    private final Field transField;

    /**
     * 目标字段对象，即需要设置翻译值的字段
     * <p>
     * 例如：UserDto类中的userName字段
     * </p>
     */
    private final Field field;

    /**
     * 提取字段的key，即从翻译数据中提取的目标字段名
     * <p>
     * 例如："name"（从用户数据中提取name字段的值）
     * </p>
     */
    private final String key;

    /**
     * 翻译注解对象
     * <p>
     * 包含翻译配置信息的注解实例
     * </p>
     */
    private final Annotation transAnno;

    /**
     * 翻译仓库类
     * <p>
     * 用于获取翻译数据的仓库实现类
     * </p>
     */
    private final Class<? extends TransRepository> repository;

    /**
     * 子属性(处理嵌套翻译)
     * <p>
     * 用于支持嵌套对象的翻译，例如：
     * <pre>
     * public class UserDto {
     *     private String userId;
     *
     *     &#64;Trans(repository = UserTransRepository.class, transKey = "userId", transField = "userName")
     *     private String userName;
     *
     *     // 嵌套对象
     *     private DepartmentDto department;
     * }
     *
     * public class DepartmentDto {
     *     private String deptId;
     *
     *     &#64;Trans(repository = DeptTransRepository.class, transKey = "deptId", transField = "deptName")
     *     private String deptName;
     * }
     * </pre>
     * </p>
     */
    private List<TransFieldMeta> children;

    /**
     * TransFieldMeta构造函数
     *
     * @param field      目标字段（需要设置翻译值的字段）
     * @param transField 源字段（包含原始值的字段）
     * @param key        提取字段的key（从翻译数据中提取的目标字段名）
     * @param repository 翻译仓库类
     * @param transAnno  翻译注解
     */
    public TransFieldMeta(Field field, Field transField, String key, Class<? extends TransRepository> repository, Annotation transAnno) {
        this.field = field;
        this.transField = transField;
        this.trans = transField.getName();
        this.key = key;
        this.repository = repository;
        this.transAnno = transAnno;
    }

    /**
     * 设置子属性列表
     * <p>
     * 用于构建嵌套翻译的树形结构。
     * <br>
     * 手动实现 setter 而非使用 @Setter 的原因：
     * - 该类大部分字段为 final，设计为不可变对象；
     * - children 字段虽可变，但仅在解析阶段一次性赋值；
     * - 使用 @Setter 会暗示“可多次修改”，易引起误解；
     * - 手动控制更清晰，符合“一次赋值、不可变”的语义。
     * </p>
     *
     * @param children 子属性列表
     */
    public void setChildren(List<TransFieldMeta> children) {
        this.children = children;
    }

}
